The test command receives options on behalf of the specified --testrunner. These are the options of the default test runner: DiscoverRunner.

Preserves the test database between test runs. This has the advantage of skipping both the create and destroy actions which can greatly decrease the time to run tests, especially those in a large test suite. If the test database does not exist, it will be created on the first run and then preserved for each subsequent run. Unless the MIGRATE test setting is False, any unapplied migrations will also be applied to the test database before running the test suite.

Randomizes the order of tests before running them. This can help detect tests that aren’t properly isolated. The test order generated by this option is a deterministic function of the integer seed given. When no seed is passed, a seed is chosen randomly and printed to the console. To repeat a particular test order, pass a seed. The test orders generated by this option preserve Django’s guarantees on test order. They also keep tests grouped by test case class.

The shuffled orderings also have a special consistency property useful when narrowing down isolation issues. Namely, for a given seed and when running a subset of tests, the new order will be the original shuffling restricted to the smaller set. Similarly, when adding tests while keeping the seed the same, the order of the original tests will be the same in the new order.

Sorts test cases in the opposite execution order. This may help in debugging the side effects of tests that aren’t properly isolated. Grouping by test class is preserved when using this option. This can be used in conjunction with --shuffle to reverse the order for a particular seed.

Sets the DEBUG setting to True prior to running tests. This may help troubleshoot test failures.

Enables SQL logging for failing tests. If --verbosity is 2, then queries in passing tests are also output.

Runs tests in separate parallel processes. Since modern processors have multiple cores, this allows running tests significantly faster.

Using --parallel without a value, or with the value auto, runs one test process per core according to multiprocessing.cpu_count(). You can override this by passing the desired number of processes, e.g. --parallel 4, or by setting the DJANGO_TEST_PROCESSES environment variable.

Django distributes test cases — unittest.TestCase subclasses — to subprocesses. If there are fewer test case classes than configured processes, Django will reduce the number of processes accordingly.

Each process gets its own database. You must ensure that different test case classes don’t access the same resources. For instance, test case classes that touch the filesystem should create a temporary directory for their own use.

Note

If you have test classes that cannot be run in parallel, you can use SerializeMixin to run them sequentially. See Enforce running test classes sequentially.

This option requires the third-party tblib package to display tracebacks correctly:

This feature isn’t available on Windows. It doesn’t work with the Oracle database backend either.

If you want to use pdb while debugging tests, you must disable parallel execution (--parallel=1). You’ll see something like bdb.BdbQuit if you don’t.

Warning

When test parallelization is enabled and a test fails, Django may be unable to display the exception traceback. This can make debugging difficult. If you encounter this problem, run the affected test without parallelization to see the traceback of the failure.

This is a known limitation. It arises from the need to serialize objects in order to exchange them between processes. See What can be pickled and unpickled? for details.

Runs only tests marked with the specified tags. May be specified multiple times and combined with test --exclude-tag.

Tests that fail to load are always considered matching.

Excludes tests marked with the specified tags. May be specified multiple times and combined with test --tag.

Runs test methods and classes matching test name patterns, in the same way as unittest's -k option. Can be specified multiple times.

Spawns a pdb debugger at each test error or failure. If you have it installed, ipdb is used instead.

Discards output (stdout and stderr) for passing tests, in the same way as unittest's --buffer option.

Django automatically calls faulthandler.enable() when starting the tests, which allows it to print a traceback if the interpreter crashes. Pass --no-faulthandler to disable this behavior.

Outputs timings, including database setup and total run time.

Shows the N slowest test cases (N=0 for all).

Python 3.12 and later

This feature is only available for Python 3.12 and later.